Inside Macintosh: QuickDraw GX Graphics /

Chapter 4 - Geometric Operations / Geometric Operations Reference

Functions / Reducing and Simplifying Shapes

GXSimplifyShape

You can use the GXSimplifyShape function to eliminate from a shape any unnecessary contour breaks, contour crossings, and internal contour loops.

void GXSimplifyShape(gxShape target);

target

A reference to the shape you want to simplify.

DESCRIPTION

The GXSimplifyShape function performs operations on the geometry of the shape specified by the target parameter and simplifies the description of the shape, sometimes changing the shape type, without affecting how the shape is drawn.

Most importantly, the resulting shape has no crossed contours. The GXSimplifyShape function adds geometric points and changes contour directions to redefine the shape's geometry so that no contour crosses over itself or any other contour.

This function also removes unnecessary contour breaks. If the last point of one contour is identical to the first point of the next contour, this function combines the two contours into a single contour.

Note

Under certain circumstances, the GXSimplifyShape function actually increases the number of geometric points and the number of contours used to defined a shape. However, the simplified shape still appears the same as the original shape when drawn.

If the geometry of the original shape can be expressed as a geometry of a simpler shape type, this function converts the shape to the simpler type. For example, if the shape referenced by the target parameter is a polygon, but the geometry of that polygon defines a simple square, the GXSimplifyShape function converts the shape to a rectangle type and redefines the geometry as appropriate. As another example, a path shape with no curved contours is converted to a polygon shape type.

The shape fill of the target shape also affects the simplifications. For example, if the target shape has two circular, concentric contours (an inner contour and an outer contour) and both contours have the same contour direction, the following occurs:

• If the shape has a winding shape fill, the inner contour does not affect how the shape is drawn. In this case, the GXSimplifyShape function removes the inner contour.
• If the shape has an even-odd shape fill, the inner contour does affect how the shape is drawn. In this case, the GXSimplifyShape function maintains the inner contour, but it reverses the direction of that contour.

As a result of these simplifications, changing the shape fill of a simplified shape from winding fill to even-odd fill or from even-odd fill to winding fill does not affect the appearance of the shape when drawn.

If you provide a target shape that is not one of the geometric shape types, this function performs the actions described in the following table:

Shape type	Action taken
bitmap	Chooses smaller color set if possible, if the pixel size is 1, 2, 4, or 8; posts the notice shape_already_in_simple_form if the pixel size is 16 or 32; converts to a rectangle shape if every pixel in the bitmap has the same color
picture	Posts the notice shape_already_in_simple_form
text	Simplifies to the empty shape if appropriate; posts the notice shape_already_in_simple_form otherwise
glyph	Simplifies to the empty shape, a text shape, or a simpler glyph shape as appropriate; posts the notice shape_already_in_simple_form if no simplification possible
layout	Simplifies to the empty shape if appropriate; posts the notice shape_already_in_simple_form otherwise

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
number_of_contours_exceeds_implementation_limit
number_of_points_exceeds_implementation_limit
size_of_path_exceeds_implementation_limit
size_of_polygon_exceeds_implementation_limit
shape_access_not_allowed
functionality_unimplemented	(debugging version)
Warnings
unable_to_traverse_open_contour_that_starts_or_ends_off_the_curve
	(debugging version)
Notices (debugging version)
shape_already_in_simple_form

SEE ALSO

For examples using this function, see "Simplifying Shapes" beginning on page 4-33.

For more information about simplified shapes, see "Reducing and Simplifying Shape Geometries" beginning on page 4-9.

For a discussion of geometric points and contours, see Chapter 2, "Geometric Shapes," in this book.

To remove unnecessary geometric points but not perform other simplifications, use the GXReduceShape function, described on page 4-74.